DOS Data List

$FF00 ; EXIT()   Program Termination

Example:
	DC.W	_EXIT

Returns: Nothing

Terminates the program.

Closes the file handles which are currently open.
Also closes the file handles opened by child processes.
Any instructions following this will not be executed.


$FF01 ; GETCHAR()   Wait for key input (with echo)

Example:
	DC.W	_GETCHAR

Returns:
	D0.L	Keycode

Waits for a key to be input and then displays the input keycode on the
standard output. The input is checked against ^C (break), ^P (switches
subsequent standard output to the printer), and ^N (reverses the action
of the ^P command). If any of those key combinations are entered,
the following will be carried out:

 ^C   Returns to the parent process
 ^P   Outputs to the printer

The keycode is returned in register D0.L


$FF02 ; PUTCHAR(CODE)   Character display

Example:
	MOVE.W	#CODE,-(SP)
	DC.W	_PUTCHAR
	ADDQ.L	#2,SP

Returns: Nothing

Displays the character corresponding to the character code specified
by CODE on the standard output. Also checks for the following input
during display:

 ^C (break)
 ^S (temporary suspension of screen display),
 ^P (switches subsequent standard output to the printer)
 ^N (reverses the action of the ^P command)



$FF03 ; COMINP()   Serial input (single byte)

Example:
	DC.W	_COMINP

Returns:
	D0.L	Single byte of input

Reads one byte from the RS-232C circuit.
Checks for ^C breaks during input.


$FF04 ; COMOUT(CODE)   Serial output (single byte)

Example:
	MOVE.W	#CODE,-(SP)
	DC.W	_COMOUT
	ADDQ.L	#2,SP

Returns: Nothing

Outputs the byte specified by CODE to the RS-232C circuit.
Checks for ^C related breaks during processing.


$FF05 ; PRNOUT(CODE)   Single character printer output

Example:
	MOVE.W	#CODE,-(SP)
	DC.W	_PRNOUT
	ADDQ.L	#2,SP

Returns:
	D0.L	-1

Outputs the character specified by CODE to the printer.
Checks for ^C related breaks during processing.


$FF06 ; INPOUT(CODE)   Keyboard input/output

Example:
	MOVE.W	#CODE,-(SP)
	DC.W	_INPOUT
	ADDQ.L	#2,SP

Returns:
	D0.L	Input character code (if CODE = $FF/$FE, otherwise 0)

Executes the following process depending on the argument, CODE:
 CODE = $FF : Key input (does not wait even if there is no input)
 CODE = $FE : Key sense (returns the input key code)
 Otherwise:   Outputs CODE as a character code

Does not perform break checks.

If CODE is $FF/$FE and the return value is 0,
it indicates that there was no input.


$FF07 ; INKEY()   single character keyboard input (no break check)

Example:
	DC.W	_INKEY

Returns:
	D0.L	Key code of the input key

Waits until a key is pressed and then returns the key code.
Does not perform break checks. See GETC() / $FF08 if you require them.


$FF08 ; GETC()   single character keyboard input (break check)

Example:
	DC.W	_GETC

Returns:
	D0.L	Key code of the input key

Waits until a key is pressed and then returns the key code.
Checks for ^C, ^P, and ^N.


$FF09 ; PRINT(MESPTR)   Character string display

Example:
	PEA	MESPTR
	DC.W	_PRINT
	ADDQ.L	#4,SP
	...
MESPTR:	DC.B	'TESTSAMPLE',$D,$A,0

Returns: Nothing

Displays the character string specified by MESPTR until the
null character (0) is reached. The address of the character string
is pushed onto the stack. Checks for ^C, ^S, ^P, and ^N.


$FF0A ; GETS(INPPTR)   Character string input

Example:
	PEA	INPPTR
	DC.W	_GETS
	ADDQ.L	#4,SP
	...
INPPTR:	DC.B	80
	DC.B	5
	DS.B	81

Returns:
	D0.L	Number of input characters

Writes the character string input by the user to the buffer specified
by INPPTR until a line break (return key) is entered. The line break
character is replaced by the null character (0) before being written
to the buffer. Checks for ^C, ^P, and ^N.

Input buffer INPPTR defines the following settings:
INPPTR+0:  DC.B n   * Maximum number of input characters
INPPTR+1:  DC.B x   * Receives the number of characters actually input
INPPTR+2:  DS.B n+1 * Receives the input. Must be large enough
                    *  to hold the maximum number of characters + 1

If the maximum number of characters is reached, a warning is issued,
but halting will not occur.

D0.L returns the same number of characters as written to INPPTR+1.
Both values represent the number of bytes from INPPTR+2 to the
null character (0; the end of the input characters) - 1.

The return/enter key code character is not included in the buffer.


$FF0B ; KEYSNS()   Key input status check

Example:
	DC.W	_KEYSNS

Returns:
	D0.L	Input status
	 =  0 : Input
	 = -1 : No input

Determines the key input status (has no effect on the buffer).
Checks for ^C, ^P, and ^N.


$FF0C ; KFLUSH(MODE,INPPTR)   Buffer flush / key input

Example:	* Example is only applicable for MODE=[1,7,8]
	PEA	INPPTR
	MOVE.W	#MODE,-(SP)
	DC.W	_KFLUSH
	ADDQ.L	#6,SP
	...
INPPTR:	DC.B	80
	DC.B	5
	DS.B	81

Returns:
	D0.L	Number of input characters

Flushes (empties) the buffer, then reads keyboard input.

The MODE argument $0? corresponds to DOS calls of the form $FF0?.
More specifically, the as below
MODE = $01 : Waits for key input and sends to std. output (i.e. w/ echo)
MODE = $06 : Key input (action differs depending on the argument)
MODE = $07 : Single character input (no break check)
MODE = $08 : Single character input (break check)
MODE = $0A : Character string input
Anything else : Only empties the buffer

Modes 6 and 10 require additional arguments.


$FF0D ; FFLUSH()   Disk reset

Example:
	DC.W	_FFLUSH

Returns: Nothing

Performs a disk reset.


$FF0E ; CHGDRV(DRIVE)   Change current drive

Example:
	MOVE.W	#DRIVE,-(SP)
	DC.W	_CHGDRV
	ADDQ.L	#2,SP

Returns:
	D0.L	Number of drives to be specified (1 to N)

Changes the current drive.

The number of the drive to change to is specified as follows:
DRIVE = 0 : A drive
DRIVE = 1 : B drive
And so on. (2, 3, 4, ... for C, D, E, ...)

D0.L returns the number of drives available (1 to N).
If the return value is less than or equal to DRIVE,
it indicates that an error occurred.



$FF0F ; DRVCTRL(MD*256+DRIVE)   Drive status check / setting

Example:
	MOVE.W	#MD*256+DRIVE,-(SP)
	DC.W	_DRVCTRL
	ADDQ.L	#2,SP

Returns:
	D0.L	Specified drive status (if MD = 0)
	 Bit 7 : LED blinking
	 Bit 6 : Ejection prohibited
	 Bit 5 : Buffer
	 Bit 4 : Ejection by user prohibited
	 Bit 3 : PRO (Protect = 1)
	 Bit 2 : RDY (Not ready = 1)
	 Bit 1 : Media insertion
	 Bit 0 : Wrong insertion
	 (PRO and RDY are returned upon media insertion when MD = 0)
	If MD is non-zero, there will be no return value.

Checks or sets the status of the drive specified by DRIVE based on
the value of MD.

The value of MD can be as follows:
 MD = 0 : Status check
 MD = 1 : Eject disk
The drive will be closed if open.
The buffer is automatically flushed (erased).
 MD = 2 : Prohibit ejection (including ejection through MD = 1)
 MD = 3 : Permit ejection
The drive will not be closed.
The buffer is automatically flushed (erased).
 MD = 4 : LED will blink if no disk is present
 MD = 5 : LED will be off if no disk is present

The drive number is specified as follows:
 DRIVE = 0 : Current drive
 DRIVE = 1 : A drive
 DRIVE = 2 : B drive


$FF10 ; CONSNS() Screen output check

Example:
	DC.W	_CONSNS

Returns:
	D0.L	output status
	 zero : output not possible
	 non-zero : output possible

Checks if screen output is possible.


$FF11 ; PRNSNS() Printer output check

Example:
	DC.W	_PRNSNS

Returns:
	D0.L	output status
	 zero : output not possible
	 non-zero : output possible

Checks if printer output is possible.


$FF12 ; CINSNS() Serial input check

Example:
	DC.W	_CINSNS

Returns:
	D0.L	input status
	 zero : input not possible
	 non-zero : input possible (input code)

Checks if input from the RS-232C circuit is possible.


$FF13 ; COUTSNS() Serial output check

Example:
	DC.W	_COUTSNS

Returns:
	D0.L	output status
	 zero : output not possible
	 non-zero : output possible

Checks if output to the RS-232C circuit is possible.


$FF14 ; System reserved


$FF15 ; System reserved


$FF16 ; System reserved


$FF17 ; FATCHK(FILE,BUFFER) File sector check

Example:
	PEA	BUFFER
	PEA	FILE
	DC.W	_FATCHK
	ADDQ.L	#8,SP
	...
FILE:	DC.B	'HUMAN.SYS',0
BUFFER:	DC.W 1
	DC.W 9
	DC.W 32
	DC.W 64
	DC.W 2
	...
	DC.W 0

Returns:
	D0.L	Number of bytes of data (including 0 at the end)
		 put into the buffer.
	D0 = 8 : Implies that the file is contiguous
	D0 < 0 : Error code

Writes the file's drive number and sector sequence to the buffer.

The buffer will be filled with data as follows:

BUFFER:	DC.W	 d	* Drive number
	DC.W	s1	* Value of the head sector
	DC.W	n1	* Number of sectors
	DC.W	s2	* Value of the next sector
	DC.W	n2	* Number of sectors
	...
	DC.W	0	* End

Drive number d is specified as follows:
d = 1 : A drive
d = 2 : B drive
d = 3 : C drive
(etc.)

With this DOS call you can check the FAT sequence,
as well as read the data part of DSKREAD directly.

Make sure you've allocated enough space for the buffer.


$FF18 ; HENDSP(MD[,POS][,MESPTR]) Kanji conversion control

Example:
	MOVE.W	#0,-(SP)	* HENDSP(0)
	DC.W	_HENDSP
	ADDQ.L	#2,SP

Returns:
	D0.L	The return value differs depending on MD

Controls the kanji conversion line.

This routine is used in application programs which use kanji conversion.
However, since it is used by the Japanese FP (kana-kanji conversion
Front Processor), general applications may not use it.

The meaning of MD, and additional arguments, are as follows:

0 (0)
 Opens the mode display window. Returns maximum number of characters.

1 (1,POS.W,MESPTR.L)
 Displays as normal. Returns the next POS.

2 (2,POS.W,MESPTR.L)
 Displays in reverse. Returns the next POS.

3 (3)
 Closes the mode display window.

4 (4)
 Opens the input window. Returns the maximum number of characters.

5 (5,POS.W,MESPTR.L)
 Displays as normal. Returns the next POS.

6 (6,POS.W,MESPTR.L)
 Displays in reverse. Returns the next POS.

7 (7,POS.W)
 Returns to the beginning after POS.

8 (8)
 Opens the candidate window. Returns the maximum number of characters.

9 (9,POS.W,MESPTR.L)
 Displays as normal. Returns the next POS.

10 (10,POS.W,MESPTR.L)
 Displays in reverse. Returns the next POS.

11 (11)
 Closes the candidate window.


$FF19 ; CURDRV() Inquires about the current drive

Example:
	DC.W	_CURDRV

Returns:
	D0.L	Current drive number
	D0.L = 0 : A drive
	D0.L = 1 : B drive
	D0.L = 2 : C drive
	(etc.)

Returns the value of the current drive.


$FF1A ; GETSS(INPPTR) Character string input

Example:
	PEA	INPPTR
	DC.W	_GETSS
	ADDQ.L	#4,SP
	...
INPPTR:	DC.B	80
	DC.B	5
	DS.B	81

Returns:
	D0.L	Number of input characters

Specifies the input buffer and writes the character string
up to the carriage return (return key) to the buffer.

Does not carry out a break check. No carriage return at VOID/NEWLINE.

A warning is issued if the maximum number of input characters
is exceeded, but it will not terminate.

See $FF0A for further information.


$FF1B ; FGETC(FILENO) Single character file handle input

Example:
	MOVE.W	#FILENO,-(SP)
	DC.W	_FGETC
	ADDQ.L	#2,SP

Returns:
	D0.L	character code of the input character

Waits until there is input from the file handle specified by FILENO.
When input is available, the next character code will be returned in D0.


$FF1C ; FGETS(INPPTR,FILENO) Character string file handle input

Example:
	MOVE.W	#FILENO,-(SP)
	PEA	INPPTR
	DC.W	_FGETS
	ADDQ.L	#6,SP
	...
INPPTR:	DC.B	80
	DC.B	5
	DS.B	81

Returns:
	D0.L	Number of input characters

Writes the input character string from the file handle specified
by FILENO -- up to the carriage return (return key) -- to the input
buffer specified by INPPTR.

The carriage return character is changed to the null character (0)
before being written to the buffer.

Does not carry out a break check. No carriage return at VOID/NEWLINE.

If the maximum amount of input characters is exceeded,
it will read input up to the maximum before terminating.



$FF1D ; FPUTC(CODE,FILENO)  Single character file handle output

Example:
	MOVE.W	#FILENO,-(SP)
	MOVE.W	#CODE,-(SP)
	DC.W	_FPUTC
	ADDQ.L	#4,SP

Returns: Nothing

The character code represented by CODE is output to the file handle
specified by FILENO. If FILENO interfaces to a character device,
this subroutine will perform a break check for ^C, ^S, ^P, and ^N.


$FF1E ; FPUTS(MESPTR,FILENO) Character string file handle output

Example:
	MOVE.W	#FILENO,-(SP)
	PEA	MESPTR
	DC.W	_FPUTS
	ADDQ.L	#6,SP
	...
MESPTR:	DC.B	'SHARP',$D,$A,0

Returns: Nothing

Outputs the character string from the pointer specified by MESPTR
to the file handle specified by FILENO.

It does not output the null character (0, which marks the end
of a character string) when it reaches the end of the string.

Performs a break check for ^C, ^S, ^P, and ^N.


$FF1F ; ALLCLOSE() Closes all file handles

Example:
	DC.W	_ALLCLOSE

Returns: Nothing

Closes all of a process's file handles which are currently open.
It also closes file handles which were opened by child processes.
It does not close file handles opened by the parent process.


$FF20 ; SUPER(STACK) Switch between Supervisor Mode / User Mode

Example:
	LEA	USERSP,SP
	CLR.L	-(SP)	* Here, STACK = 0
	DC.W	_SUPPER
	ADDQ.L	#4,SP	* (SP) is trashed, so discard it

	MOVE.L	D0,SSPBUF
	MOVE.L	USP,A0
	MOVE.L	A0,USPBUF

	...	* Additional code in Supervisor Mode

	MOVE.L	USPBUF,A0
	MOVE.L	A0,USP

	MOVE.L	SSPBUF,-(SP)
	DC.W	_SUPER
	ADDQ.L	#4,SP	* (SP) is trashed, so discard it
	...
USPBUF:	DC.L	0	* USP BUFFER
SSPBUF:	DC.L	0	* SSP BUFFER

Returns:
	D0.L	If STACK = 0, this will be the previous value of SSP.
		The return value will be negative if an error occurred.

Switches between Supervisor Mode and User Mode.

The characteristics of STACK are defined as follows:
STACK  = 0 : USP is copied to SSP, context switches to Supervisor Mode.
STACK >< 0 : STACK is copied to SSP, context switches to User Mode.


$FF21 ; FNCKEY(MD*256+FNO,BUFFER) Read/set redefinable keys

Example:
	PEA	BUFFER
	MOVE.W	#MD*256+FNO,-(SP)
	DC.W	_FNCKEY
	ADDQ.L	#6,SP
	...
BUFFER:	DS.B	32

Returns:
	D0.L	 0 : Normal return
		-1 : Bad key number

Reads/sets (depending on the value of MD) one or more redefinable keys.
This DOS call is supported by the CON device (console).

There are 2 possible settings for MD:
 MD = 0 : Read
 MD = 1 : Set (The function key can be displayed at the same time,
               but it does not display it in 32-line mode.)

FNO has the following meaning:
  0 : all the keys
  1 to 10 : F1 to F10
 11 to 20 : SHIFT + F1 to F10
 21 : ROLL UP
 22 : ROLL DOWN
 23 : INS
 24 : DEL
 25 : UP (^)
 26 : LEFT (<-)
 27 : RIGHT(->)
 28 : DOWN (v)
 29 : CLR
 30 : HELP
 31 : HOME
 32 : UNDO

BUFFER is the data buffer for reading/setting.
The size of the buffer depends on the value of FNO:
 FNO =        0 : 712 bytes (20*32 + 12*6)
 FNO =  1 to 20 :  32 bytes (31 bytes + $00)
 FNO = 21 to 32 :   6 bytes ( 5 bytes + $00)


$FF22 ; KNJCTRL(MD,??) Kana-kanji conversion function call

Example: Not available

Returns: D0.L

This function call is used by the Japanese FP.
Please refer to Chapter 4 of the Programmer's Manual for more details.


$FF23 ; CONCTRL(MD[,etc...]) Console control

Example:
	MOVE.W	#Y,-(SP)
	MOVE.W	#X,-(SP)
	MOVE.W	#3,-(SP)	; MD = 3
	DC.W	_CONCTRL
	ADDQ.L	#6,SP

Returns:
	D0.L	0 : Successful completion

Provides direct control over the console.
This DOS call is supported by the CON device.

The value of MD is as follows:

MD = 0 : CONCTRL( 0,CD)
Displays the byte specified by CD.

MD = 1 : CONCTRL( 1,MESPTR)
Displays the character string data specified by MESPTR.
The character string data must end with the null character (0).

MD = 2 : CONCTRL( 2,ATR)
Sets the attribute specified by ATR.

MD = 3 : CONCTRL( 3,X,Y)
Set the cursor position specified by X and Y.

MD = 4 : CONCTRL( 4)
Moves the cursor one line down. Scrolls up when on the bottom line.

MD = 5 : CONCTRL( 5)
Moves the cursor one line up. Scrolls down when on the top line.

MD = 6 : CONCTRL( 6,N)
Moves the cursor N lines up. Does not scroll. N=0 is the same as N=1.

MD = 7 : CONCTRL( 7,N)
Moves the cursor N lines down. Does not scroll. N=0 is the same as N=1.

MD = 8 : CONCTRL( 8,N)
Moves the cursor N columns to the right. Does not scroll.
N=0 is the same as N=1.

MD = 9 : CONCTRL( 9,N)
Moves the cursor N columns to the left. Does not scroll.
N=0 is the same as N=1.

MD = 10 : CONCTRL(10,MOD)
Clears some or all of the screen, depending on the value of MOD:
 MOD = 0 : Clears the screen from the cursor position to the right side.
 MOD = 1 : Clears the screen from the left side to the cursor position.
 MOD = 2 : Clears the whole screen. The cursor returns to home position.

MD = 11 : CONCTRL(11,MOD)
Clears some or all of the current line, depending on the value of MOD:
 MOD = 0 : Clears the line from the cursor position to the right edge.
 MOD = 1 : Clears the line from the left edge to the cursor position.
 MOD = 2 : Clears the entire line.

MD = 12 : CONCTRL(12,N)
Inserts N lines from the cursor's position. N=0 is the same as N=1.

MD = 13 : CONCTRL(13,N)
Deletes N lines from the cursor's position. N=0 is the same as N=1.

MD = 14 : CONCTRL(14,MOD)
Sets the mode of the function key line, based on the value of MOD.
Resets the range of scroll.

The format of MOD in this mode is as follows:
 MOD =  0 : Displays the function keys. Scroll range is (0,31).
 MOD =  1 : Displays the shift functions. Scroll range is (0,31).
 MOD =  2 : Does not display anything. Scroll range is (0,31).
 MOD =  3 : Does not distinguish the function keys
             with the one of another line. Scroll range is (0,32).
 MOD = -1 : Returns the current mode in D0.
Returns the previous mode in D0.L

MD = 15 : CONCTRL(15,YS,YL)
Sets the scroll range to YS,YL.
The cursor moves to the home position after scrolling.
The value of YS+YL can be set as high as 32 when the mode of the
function key line is 3 (MD=14, MOD=3), else it is limited to 31.
The absolute coordinates (0,YS) become logical coordinates (0,0).

MD = 16 : CONCTRL(16,MOD)
Selects the screen size specified by MOD:
 MOD = 0 : High resolution 768*512, no graphics.
 MOD = 1 : High resolution 768*512, 16-color graphics.
 MOD = 2 : High resolution 512*512, no graphics.
 MOD = 3 : High resolution 512*512, 16-color graphics.
 MOD = 4 : High resolution 512*512, 256-color graphics.
 MOD = 5 : High resolution 512*512, 65536-color graphics.
 MOD =-1 : Checks the current mode.
Returns the previous mode in D0.L

MD = 17 : CONCTRL(17)
Sets the mode wherein the cursor is displayed.

MD = 18 : CONCTRL(18)
Sets the mode wherein the cursor is not displayed.
If the call succeeds, the value of D0.L will be 0.


$FF24 ; KEYCTRL(MD[,GROUP][,INSMODE]) Console input

Example:
	CLR.W	-(SP)
	MOVE.W	#4,-(SP)
	DC.W	_KEYCTRL
	ADDQ.L	#4,SP

Returns:
	D0.L	Dependent on the value of MD.

Can perform direct input from the console as well as query its status.
This DOS call is supported by the CON device.

The value of MD is as follows:

MD = 0 : KEYCTRL(0)
Gets keyboard input. The key code of the input key is returned in D0.L

MD = 1 : KEYCTRL(1)
Asynchronous keyboard input.
Returns the key code in D0.L or 0 if nothing was pressed.

MD = 2 : KEYCTRL(2)
Checks the state of the shift keys.
Each bit in D0.L corresponds to a shift key as follows (1=on):
 bit 10 : Full-width key
 bit  9 : Hiragana key
 bit  8 : INS key
 bit  7 : CAPS key
 bit  6 : Code input key
 bit  5 : Romaji key
 bit  4 : Kana key
 bit  3 : OPT2 key
 bit  2 : OPT1 key
 bit  1 : CTRL key
 bit  0 : SHIFT key

MD = 3 : KEYCTRL(3,GROUP)
Returns the status of the key-code group specified by GROUP in D0.L.
Refer to IOCS call $04 (BITSNS) for the relationship between the
key-code groups and their respective keys.

MD = 4 : KEYCTRL(4,INSMODE)
The value of INSMODE will be set as follows:
 INSMODE = $FF : INS key on
 INSMODE = $00 : INS key off


$FF25 ; INTVCS(INTNO,JOBADR) Vector address specification

Example:
	PEA	JOBADR
	MOVE.W	#INTNO,-(SP)
	DC.W	_INTVCS
	ADDQ.L	#6,SP
	...
JOBADR:	RTE		* For vectors from $00 to $3FF
JOBADR:	RTS		* For a Human68K DOS call

Returns:
	D0.L	Previous INTNO vector value

Replaces the vector specified by INTNO with JOBADR.

The interrupt handlers (from $0 to $3FF) are from $00 to $FF.
The IOCS calls are from  $100 to  $1FF.
The  DOS calls are from $FF00 to $FFFF.


$FF26 ; PSPSET(PSPADR) Program termination buffer

Example:
	MOVE.L	#PSPADR,-(SP)
	DC.W	_PSPSET
	ADDQ.L	#4,SP
	...
PSPADR:	DC.L	MEMADR	* Storage for the address returned by MALLOC.

Returns: Nothing

When the program ends, records several kinds of information to the
buffer specified by PSPADR. The size of the data written is 240 bytes.

The buffer pointer PSPADR must be the address of the memory management
pointer + $10. Specify the address returned by MALLOC ($FF48) there.


$FF27 ; GETTIM2() Get the current time

Example:
	DC.W	_GETTIM2

Returns:
	D0.L	Current time: $00HHMMSS

Requests the current time.

The time data is formatted as follows, in 8-bit divisions:

D0.L = 0 | hours (0 to 23) | minutes (0 to 59) | seconds (0 to 59)

The difference from GETTIME ($FF2C) is that seconds are specified with
a precision of a single second, such that the result exceeds 16 bits.


$FF28 ; SETTIM2(TIME) Sets the current time

Example:
	MOVE.L	#TIME,-(SP)	; $00HHMMSS
	DC.W	_SETTIM2
	ADDQ.L	#4,SP

Returns:
	D0.L	Error code

Set the time to the value of TIME.

The time data is formatted as follows, in 8-bit divisions:

D0.L = 0 | hours (0 to 23) | minutes (0 to 59) | seconds (0 to 59)

The difference from SETTIME ($FF2D) is that seconds are specified with
a precision of a single second, such that the value exceeds 16 bits.


$FF29 ; NAMESTS(FILE,BUFFER) Read information about a file

Example:
	PEA	BUFFER
	PEA	FILE
	DC.W	_NAMESTS
	ADDQ.L	#8,SP
	...
	FILE:	DC.B	'B:\TEST\ABCDEFGHIJKLMN.S',0
	BUFFER:	DS.B	88

Returns:
	D0.L	Error code

Writes information about a file, indicated by FILE, to BUFFER.

The buffer receives 88 bytes formatted as follows:

BUFFER:
NAMWLD: DS.B 1	* If 0, no wild, if $FF, no file specification.
NAMDRV: DS.B 1	* Drive specification: A=0, B=1, etc.
NAMPTH: DS.B 65	* Path to file
NAMNM1: DS.B 8	* File name (up to 8 leading characters)
NAMEXT: DS.B 3	* File name extension
NAMNM2: DS.B 10	* File name (last 10 characters)

The drive number is as follows:
 0 : A drive
 1 : B drive
 2 : C drive

The path includes the root symbol (\) and, if available, the name
of any sub-directories, each followed by a directory separator (\).

The expected results of the above example call are as follows:

BUFFER:	DC.B	0	* File name specified without using a wild card
	DC.B	1	* Drive B
	DC.B	'\TEST\',0
	DS.B	65-7	* Remaining unused part of the preceding field
	DC.B	'ABCDEFGH'
	DC.B	'S',0,0
	DC.B	'IJKLMN',0,0,0,0


$FF2A ; GETDATE() Gets the current date

Example:
	DC.W	_GETDATE

Returns:
	D0.L	Current date

The individual bits of the date are to be interpreted as follows:

 31 to 19 : 0
 18 to 16 : Day of the week (0 to 6)
 15 to 09 : Year - 1980 (0 to 119)
 08 to 05 : Month (1 to 12) (January to December)
 04 to 00 : Day (1 to 31)

The days of the week (0 to 6) correspond to Sunday through Saturday.

The year is stored as a value from 0 to 119, calculated by subtracting
1980 from the current year, going by the Western calendar.


$FF2B ; SETDATE(DATE) Sets the current date

Example:
	MOVE.W	#DATE,-(SP)
	DC.W	_SETDATE
	ADDQ.L	#2,SP

Returns:
	D0.L	Error code

The individual bits of DATE are defined as follows:

15 to 09 : Year -1980(0 to 119)
08 to 05 : Month (1 to 12) (January to December)
04 to 00 : Day (1 to 31)

The year is stored as a value from 0 to 119, calculated by subtracting
1980 from the current year, going by the Western calendar.


$FF2C ; GETTIME() Gets the current time

Example:
	DC.W	_GETTIME

Returns:
	D0.W	Current time

The individual bits of the result are defined as follows:

 15 to 11 : Hours (0 to 23)
 10 to 05 : Minutes (0 to 59 minutes)
 04 to 00 : Seconds (0 to 29 double seconds)

The seconds are specified with a precision of two seconds.
Therefore, the acceptable range of values is from 0 to 29.

The only difference from GETTIM2 ($FF27) is that the seconds are
less precise, such that the return value fits within 16 bits.


$FF2D ; SETTIME(TIME) Sets the current time

Example:
	MOVE.W	#TIME,-(SP)
	DC.W	_SETTIME
	ADDQ.L	#2,SP

Returns:
	D0.L	Error code

The individual bits of the date to be set are as follows:

 15 to 11 : Hours (0 to 23)
 10 to 05 : Minutes (0 to 59 minutes)
 04 to 00 : Seconds (0 to 29 double seconds)

The seconds are specified with a precision of two seconds.
Therefore, the acceptable range of values is from 0 to 29.


The only difference from SETTIM2 ($FF28) is that the seconds
are less precise, such that the value fits within 16 bits.


$FF2E ; VERIFY(FLG) Sets/clears the verify flag

Example:
	MOVE.W	#FLAG,-(SP)
	DC.W	_VERIFY
	ADDQ.L	#2,SP

Returns: Nothing

The contents of the verify flag are as follows:
FLAG = 0 : No verification
FLAG = 1 : Verification


$FF2F ; DUP0(FILENO,NEWNO) File handle forced duplication

Example:
	MOVE.W	#NEWNO,-(SP)
	MOVE.W	#FILENO,-(SP)
	DC.W	_DUP0
	ADDQ.L	#4,SP

Returns:
	D0.L	Previous value of NEWNO or a negative number on error

The FILENO file handle (of a file which is currently open) is forcibly
duplicated onto the second file handle, NEWNO. Thus a single file is
provided with multiple file handles and you can manipulate the same
file using several different handles.

You can change the file handle for CTTY with DUP ($FF45) / DUP2 ($FF46).
When you call CLOSE, it returns to this number.

The valid range for NEWNO is from 0 to 4 with this command.
Use DUP2 ($FF46) for values beyond this.

D0.L receives the previous value of NEWNO.
A negative result indicates an error occurred.

The following sequence of calls will turn the
standard input/output/error streams into AUX:

 DUP0(3,2)
 DUP0(3,1)
 DUP0(3,0)

The following sequence will restore them:

 DUP0(2,2)
 DUP0(1,1)
 DUP0(0,0)


$FF30 ; VERNUM() Returns the OS version

Example:
	DC.W	_VERNUM

Returns:
	D0.L	Version number

High word : '68'
Low  word : Major version number * $100 + minor version number


$FF31 ; KEEPPR(PRGLEN,CODE) Terminate and stay resident

Example:
	MOVE.W	#CODE,-(SP)
	MOVE.L	#PRGLEN,-(SP)
	DC.W	_KEEPPR

Returns: Nothing

Terminates the process (PSP part not included) while leaving PRGLEN
bytes resident. CODE is the program exit code.

Closes all open file handles, including those opened by child processes.


$FF32 ; GETDPB(DRIVE,DPBPTR) Copies a device's drive parameter block

Example:
	PEA	DPBPTR
	MOVE.W	#DRIVE,-(SP)
	DC.W	_GETDPB
	ADDQ.L	#6,SP
	...
DPBPTR:	DS.B	94

Returns:
	D0.L	Error code if negative

The drive number is as follows:
 DRIVE = 0 : Current drive
 DRIVE = 1 : A drive
 DRIVE = 2 : B drive
 DRIVE = 3 : C drive

The write buffer DPBPTR contains 94 bytes and the format is as follows:

DPBPTR:	DC.B	* Drive number: 0 = A, 1 = B, etc.
	DC.B	* Unit number used with the device driver
	DC.W	* Number of bytes per sector
	DC.B	* Number of sectors per cluster - 1
	DC.B	* Cluster <-> sector shift count
	DC.W	* FAT starting sector number
	DC.B	* Number of FATs
	DC.B	* Number of FAT sectors (excluding duplicates)
	DC.W	* Number of root directories
	DC.W	* Starting sector number of the data area
	DC.W	* Total clusters + 1
	DC.W	* Starting sector number of the root directory
	DC.L	* Pointer to device driver
	DC.B	* Media byte
	DC.B	* DPB in-use flag (not accessible if -1)
	DC.L	* Pointer to the next DPB
	DC.W	* Current directory's cluster number (0 for root)
	DS.B 64	* Current directory's character buffer.


$FF33 ; BREAKCK(FLG) Sets the break check

Example:
	MOVE.W	#FLAG,-(SP)
	DC.W	_BREAKCK
	ADDQ.L	#2,SP

Returns:
	D0.L	Result
		0 : Break checks only during a subset of DOS calls
		1 : Break checks for all DOS calls.

The DOS break-check configuration will be set according to the value
of FLAG as specified below.

 FLAG =  0 : Perform break checks only during a subset of DOS calls
 FLAG =  1 : Perform break checks for all DOS calls.
 FLAG = -1 : Checks the configuration

The subset of DOS calls mentioned above is as follows:

GETCHAR($FF01)  PRINT($FF09)
PUTCHAR($FF02)   GETS($FF0A)
 COMINP($FF03) KEYSNS($FF0B)
 COMOUT($FF04) KFLUSH($FF0C)
 PRNOUT($FF05)  FPUTC($FF0D)
   GETC($FF08)  FPUTS($FF0E)

[Warning: The documentation for this call does not match DOSCALL.MAN]



$FF34 ; DRVXCHG(OLD,NEW) Swaps drives

Example:
	MOVE.W	#NEW,-(SP)
	MOVE.W	#OLD,-(SP)
	DC.W	_DRVXCHG
	ADDQ.L	#4,SP

Returns: Nothing

Exchanges the OLD drive and the NEW drive.

The drive numbers are indicated by the following values:
 0 : Current drive
 1 : A drive
 2 : B drive


$FF35 ; INTVCG(INTNO) Acquires the current value of a vector

Example:
	MOVE.W	#INTNO,-(SP)
	DC.W	_INTVCG
	ADDQ.L	#2,SP

Returns:
	D0.L	Vector value

The interrupt handlers (from $0 to $3FF) are from $00 to $FF.
The Human68k DOS calls are from $FF00 to $FFFF.


$FF36 ; DSKFRE(DRIVE,BUFFER) Evaluates the remaining disk capacity

Example:
	PEA	BUFFER
	MOVE.W	#DRIVE,-(SP)
	DC.W	_DSKFRE
	ADDQ.L	#6,SP
	...
BUFFER:	DS.W	1
	DS.W	1
	DS.W	1
	DS.W	1

Returns:
	D0.L	Bytes available (up to 2 GB) or negative on error

Checks the remaining capacity of the disk drive specified by DRIVE.
Writes the result to the buffer specified by BUFFER.

The buffer contains 8 bytes and is formatted as follows:

BUFFER:	DS.W	1	* Number of free clusters
	DS.W	1	* Total number of clusters
	DS.W	1	* Number of sectors per cluster
	DS.W	1	* Number of bytes per sector


$FF37 ; NAMECK(FILE,BUFFER) Splits a file name into components

Example:
	PEA	BUFFER
	PEA	FILE
	DC.W	_NAMECK
	ADDQ.L	#8,SP
	...
FILE:	DC.B	'B:\TEST\ABCDEFGHIJKLMN.S',0
BUFFER:	DS.B	92

Returns:
	D0.L	$FF : No file specified
		$00 : No wild cards used
		Negative number : Error code
		Else : Wild cards were used

Splits up the fully qualified path specified by FILE into BUFFER.
If an error occurs, BUFFER will not contain meaningful data.

BUFFER contains 91 bytes formatted as follows:

BUFFER:	DC.B	'?:'	* Drive letter and colon
	DS.B	64+1	* Path (null-terminated)
	DS.B	18+1	* File name (max 18 bytes + null terminator)
	DS.B	1+3+1	* Extension (includes period & null terminator)

The path includes the root symbol (\) and, if available, the name
of any sub-directories, each followed by a directory separator (\).

The expected results of the above example call are as follows:

BUFFER:	DC.B	'B:'
	DC.B	'\TEST\',0
	DS.B	65-7		* Unused remainder of the previous field
	DC.B	'ABCDEFGHIJKLMN',0
	DS.B	19-15		* Unused remainder of the previous field
	DC.B	'.S',0
	DS.B	5-3		* Unused remainder of the previous field


$FF39 ; MKDIR(NAMEPTR) Creates a directory

Example:
	PEA	NAMEPTR
	DC.W	_MKDIR
	ADDQ.L	#4,SP
	...
NAMEPTR:DC.B	'A:\DOC',0

Returns:
	D0.L	Error code if negative

Creates a directory with the name specified by NAMEPTR.


$FF3A ; RMDIR(NAMEPTR) Removes a directory

Example:
	PEA	NAMEPTR
	DC.W	_RMDIR
	ADDQ.L	#4,SP
	...
NAMEPTR:DC.B	'A:\DOC',0

Returns:
	D0.L	Error code if negative

Removes the directory specified by NAMEPTR. The directory must be empty.
You can't remove the current directory or the root directory.


$FF3B ; CHDIR(NAMEPTR) Changes the current directory

Example:
	PEA	NAMEPTR
	DC.W	_CHDIR
	ADDQ.L	#4,SP
	...
NAMEPTR:DC.B	'A:\DOC',0

Returns:
	D0.L	Error code if negative

Changes the current directory to the directory specified by NAMEPTR.
The directory must already exist.


$FF3C ; CREATE(NAMEPTR,ATR) File creation (called CREAT in the manual)

Example:
	MOVE.W	#ATR,-(SP)
	PEA	NAMEPTR
	DC.W	_CREATE
	ADDQ.L	#6,SP
	...
NAMEPTR:DC.B	'A:\DOC\TEST.DOC',0

Returns:
	D0.L	File handle of the created file or a negative error code

Creates a new file.

If the specified file name already exists, you will lose the contents
of the original file.

ATR defines the attributes of the file to be created.
The meaning of each bit is as follows:
 15 to 06 : Ignored
 05 : A - Archive
 04 : D - Directory name
 03 : V - Volume name
 02 : S - System file
 01 : H - Hidden file
 00 : R - Read-only file

If the file is successfully created, the file handle will be returned
in D0.L, otherwise a negative error code will be returned.


$FF3D ; OPEN(NAMEPTR,MODE) Opens a file for reading/writing

Example:
	MOVE.W	#MODE,-(SP)
	PEA	NAMEPTR
	DC.W	_OPEN
	ADDQ.L	#6,SP
	...
NAMEPTR:DC.B	'A:\DOC\TEST.DOC',0

Returns:
	D0.L	File handle of the opened file or a negative error code

Opens the file specified by NAMEPTR.
The file access method is specified by MODE.

Opens the file NAMEPTR with the file access method selected by MODE.

MODE is defined as follows:
MODE =    0 : Opens in read-only  mode
MODE =    1 : Opens in      write mode
MODE =    2 : Opens in read/write mode
MODE = $100 : Opens in read-only  mode (dictionary)
MODE = $101 : Opens in      write mode (dictionary)
MODE = $102 : Opens in read/write mode (dictionary)

The dictionary modes return a handle exclusively for dictionaries.
Users may not use it.

If the file is successfully opened, the file handle will be returned
in D0.L, otherwise a negative error code will be returned.


$FF3E ; CLOSE(FILENO) Closes a file handle

Example:
	MOVE.W	#FILENO,-(SP)
	DC.W	_CLOSE
	ADDQ.L	#2,SP

Returns:
	D0.L	Error code if negative

Closes the file handle specified by FILENO.


$FF3F ; READ(FILENO,DATAPTR,SIZE) Reads from a file

Example:
	MOVE.L	#SIZE,-(SP)
	PEA	DATAPTR
	MOVE.W	#FILENO,-(SP)
	DC.W	_READ
	LEA	10(SP),SP
	...
DATAPTR:DS.B	SIZE

Returns:
	D0.L	Number of bytes actually read or negative on error

Reads SIZE bytes of data from the file handle specified by FILENO
into the DATAPTR buffer.

The read operation starts at the current position of the file pointer.
Upon completion, the file pointer will be positioned immediately after
the last byte read.

Note that you cannot restore the stack with a single ADDQ.L
after this call returns; it is recommended to use LEA instead.


$FF40 ; WRITE(FILENO,DATAPTR,SIZE) Writes to a file

Example:
	MOVE.L	#SIZE,-(SP)
	PEA	DATAPTR
	MOVE.W	#FILENO,-(SP)
	DC.W	_WRITE
	LEA	10(SP),SP
	...
DATAPTR:DC.B	DATA,DATA,DATA,...

Returns:
	D0.L	Number of bytes actually written or negative on error

Writes SIZE bytes of data from the DATAPTR buffer to the file
associated with the file handle FILENO.

The writing process starts at the current position of the file pointer.
Upon completion, the file pointer will be positioned immediately after
the last byte written.

Note that you cannot restore the stack with a single ADDQ.L
after this call returns; it is recommended to use LEA instead.


$FF41 ; DELETE(NAMEPTR) File deletion

Example:
	PEA	NAMEPTR
	DC.W	_DELETE
	ADDQ.L	#4,SP
	...
NAMEPTR:DC.B	'A:\TEST.DOC',0

Returns:
	D0.L	Error code if negative

Deletes the file specified by NAMEPTR.

Won't work with wild cards or directories.


$FF42 ; SEEK(FILENO,OFFSET,MODE) File pointer movement

Example:
	MOVE.W	#MODE,-(SP)
	MOVE.L	#OFFSET,-(SP)
	MOVE.W	#FILENO,-(SP)
	DC.W	_SEEK
	ADDQ.L	#8,SP

Returns:
	D0.L	Current file position or a negative error code

Moves the file pointer linked to FILENO by OFFSET bytes (which can be
either a positive or negative number). The movement is relative to one
of three possible locations, as defined by the MODE argument.

 MODE = 0 : Offset is relative to the beginning
 MODE = 1 : Offset is relative to the current position
 MODE = 2 : Offset is relative to the end

After the file pointer is moved with this command,
a subsequent file operation will occur at the new position.

SEEK can move pointers anywhere in a file. It can also move pointers
beyond the current end of a file, but an error occurs when attempting
to position the file pointer further back than the start of the file.


$FF43 ; CHMOD(NAMEPTR,ATR) Changes file attributes

Example:
	MOVE.W	#ATR,-(SP)
	PEA	NAMEPTR
	DC.W	_CHMOD
	ADDQ.L	#6,SP
	...
NAMEPTR:DC.B	'A:\DOC\TEST.DOC',0

Returns:
	D0.L	The specified file attributes or a negative error code

Changes the attributes of the file specified by NAMEPTR.

The individual bits of ATR are defined as follows:
 15 to 06 : Ignored
 05 : A - Archive
 04 : D - Directory name
 03 : V - Volume name
 02 : S - System file
 01 : H - Hidden file
 00 : R - Read-only file

If -1 is passed for the ATR argument, the file attributes will be read
without being modified.


$FF44 ; IOCTRL(MD[,DT,...]) Direct I/O through device driver's IOCTRL

Example:
	MOVE.L	#LEN,-(SP)
	PEA	PTR
	MOVE.W	#FILENO,-(SP)
	MOVE.W	#2,-(SP)	; MD = 2
	DC.W	_IOCTRL
	LEA	12(SP),SP
	...
PTR:	DS.B	LEN

Returns:
	D0.L	(Results vary depending on the value of MD.)
		Device information
		Number of bytes read
		Number of bytes written
		Input status
		Output status

Performs device driver I/O directly.

Several distinct operations are available depending on the value of MD.

MD = 0 : IOCTRL(0,FILENO.W)
Returns (in D0.L) device information about the file handle FILENO.

MD = 1 : IOCTRL(1,FILENO.W,DT.W)
Sets the device information (DT) in the handle specified by FILENO.
Returns the previous device information in D0.L.

MD = 2 : IOCTRL(2,FILENO.W,PTR.L,LEN.L)
Reads LEN bytes from FILENO into the PTR buffer.
Returns the number of bytes read in D0.L.

MD = 3 : IOCTRL(3,FILENO.W,PTR.L,LEN.L)
Writes LEN bytes from the PTR buffer to FILENO.
Returns the number of bytes written in D0.L.

MD = 4 : IOCTRL(4,DRIVE.W,PTR.L,LEN.L)
Reads from device number given by DRIVE (0 = current, 1 = A, etc.).
Returns the number of bytes read in D0.L.

MD = 5 : IOCTRL(5,DRIVE.W,PTR.L,LEN.L)
Writes to the device number given by DRIVE (0 = current, 1 = A, etc.).
Returns the number of bytes written in D0.L.

MD = 6 : IOCTRL(6,FILENO.W)
Returns, in D0.L, the input status of the handle specified by FILENO.
The result is interpreted as follows:
 D0.L = $FF : Input possible
 D0.L = $00 : Input not possible

MD = 7 : IOCTRL(7,FILENO.W)
Returns, in D0.L, the output status of the handle specified by FILENO.
The result is interpreted as follows:
 D0.L = $FF : Output possible
 D0.L = $00 : Output not possible

Input/output is not possible when the IOCTRL bit of the device header
of the device driver is 0.

The individual bits of the device information (DT) are defined below.

    0 : Standard input
    1 : Standard output
    2 : NULL
    3 : CLOCK
    4 : (reserved)
    5 : RAW (1) / COOKED (0)
    6 : (reserved)
    7 : Character device ( 1) / block device ( 0)
 8~14 : (reserved)
   15 : IOCTRL possible (1) / not possible (0)


$FF45 ; DUP(FILENO) File handle duplication

Example:
	MOVE.W	#FILENO,-(SP)
	DC.W	_DUP
	ADDQ.L	#2,SP

Returns:
	D0.L	The new file handle or a negative error code

The file handle (FILENO) of a currently open file is duplicated,
creating a second file handle.

Since file handles of identical files uses the same file pointer,
you can use any of the file handles to perform file operations.

The new file handle is returned in D0.L.
A negative number indicates an error code.


$FF46 ; DUP2(FILENO,NEWNO) File handle forced duplication

Example:
	MOVE.W	#NEWNO,-(SP)
	MOVE.W	#FILENO,-(SP)
	DC.W	_DUP2
	ADDQ.L	#4,SP

Returns:
	D0.L	Error code if negative

The handle (FILENO) of a currently open file is forcibly duplicated,
creating a second file handle (NEWNO).

If the file handle specified by NEWNO is already open,
it will be automatically closed prior to duplication.

Since identical file handles use the same file pointer,
either file handle can be used to manipulate the file.


$FF47 ; CURDIR(DRIVE,PATHBUF) Gets the current directory name

Example:
	PEA	PATHBUF
	MOVE.W	#DRIVE,-(SP)
	DC.W	_CURDIR
	ADDQ.L	#6,SP
	...
PATHBUF:DS.B	65

Returns:
	D0.L	Error code

Writes the name of the current directory for the drive specified
by DRIVE to the PATHBUF buffer (which must be at least 65 bytes).

The drive number is specified as follows:
 DRIVE = 0 : Current drive
 DRIVE = 1 : A drive
 DRIVE = 2 : B drive

The leading and trailing separators (\) are not included,
as demonstrated in the following examples.

PATHBUF: DC.B	0	* If the root directory is the current directory
PATHBUF: DC.B	'DOC',0	* If \DOC is the current directory


$FF48 ; MALLOC(LEN) Memory allocation

Example:
	MOVE.L	#LEN,-(SP)
	DC.W	_MALLOC
	ADDQ.L	#4,SP

Returns:
	D0.L	Pointer to the work area of the allocated memory

Allocates and returns a pointer to LEN bytes of memory.
Only the lower 24 bits of LEN are valid.

D0.L receives a pointer to usable portion of the secured memory.
(The MSP will be $10 bytes below this address).

If the allocation fails, the subroutine will return $81000000 plus
the greatest number of bytes that could be successfully allocated.

If $8200000X is returned, it indicates that any memory allocation
is currently impossible. In this case, the lowest 4 bits (X) of the
result are indeterminate.


$FF49 ; MFREE(MEMPTR) Frees a memory block

Example:
	MOVE.L	MEMPTR,-(SP)
	DC.W	_MFREE
	ADDQ.L	#4,SP
	...
MEMPTR:	DC.L	X	* The work area returned by a call to MALLOC

Returns:
	D0.L	Error code

Frees the memory block specified by MEMPTR.

MEMPTR is the address returned by MALLOC (the pointer to the usable
part of the allocated memory).

An error occurs if an irregular MEMPTR is passed to this subroutine.

If MEMPTR is 0, all the memory allocated by the caller will be freed,
to include all memory allocations of the child processes, if any.


$FF4A ; SETBLOCK(MEMPTR,NEWLEN) Changes a memory block

Example:
	MOVE.L	#NEWLEN,-(SP)
	MOVE.L	MEMPTR,-(SP)
	DC.W	_SETBLOCK
	ADDQ.L	#8,SP
	...
MEMPTR:	DC.L	X	* The work area returned by a call to MALLOC

Returns:
	D0.L	Error code

Changes the size of the memory block specified by MEMPTR.
The memory area can be expanded or contracted with this call.
Only the lower 24-bits of NEWLEN are valid.

MEMPTR must be an extant address allocated through MALLOC.
An error occurs if an irregular MEMPTR is passed to this subroutine.

If the reallocation fails, the subroutine will return $81000000 plus
the greatest number of bytes that could be successfully allocated.

If $8200000X is returned, it indicates that any memory allocation
is currently impossible. In this case, the lowest 4 bits (X) of the
result are indeterminate.


$FF4B ; EXEC(MD,FIL,P1,P2) Loads a program

Example:
	CLR.L	-(SP)
	PEA	P1
	PEA	FIL
	MOVE.W	#0,-(SP)	* MD = 0
	DC.W	_EXEC
	LEA	14(SP),SP
	...
P1:	DC.B	11	* Number of characters in the argument string
	DC.B	'DOSCALL.DOC',0
FIL:	DC.B	'EDIT.X',0

Returns:
	D0.L		Process exit code, or a negative error code
		 	 if the process fails to load/execute
	D1-D7/A0-A6	Destroyed if the process returns

	When MD = 1:
		A0	PSP - $10 (memory management pointer)
		A1	DATAEND (last address allocated to the program)
		A2	Command line
		A3	Environment pointer
		A4	Execution address

Loads and/or executes a program.

If the return value in D0.L is negative, the program could not be
loaded/executed. If positive, the results vary according to the mode.

For modes 0 and 1, additional values are returned in A0 through A4.

When executing a program, the contents of the registers from D1 to D7
and A0 to A6 are not guaranteed.

The behavior of this call changes according to the value of MD:

	MD = 0

Loads and executes the program specified by FIL.

P1 is the command line arguments and P2 is the environment pointer.
If P2 is 0, the environment will be the same as the current environment.

The following values are available to the new program:
 A0 = PSP - $10 (memory management pointer)
 A1 = DATAEND (last address allocated to the program)
 A2 = Command line
 A3 = Environment pointer
 A4 = Execution address

In a sense, the above represents the "return values" from this call,
as seen by the program being executed.

	MD = 1

Loads, but does not execute, the program specified by FIL.

P1 is the command line arguments and P2 is the environment pointer.
If P2 is 0, the environment will be the same as the current environment.

D0.L receives the execution address of the loaded program.
If an error occurs, a negative number will be returned instead.

A0 - A4 are initialized the same way as when MD = 0.

	MD = 2

This invocation looks up PATH from P2's environment, separates the
command line passed in FIL into a file name (including drive name/path)
and arguments, then writes the results to the FIL and P1 buffers.

FIL and P1 must contain as least 90 bytes and 256 bytes respectively.

If P2 is 0, PATH will be looked up from the current environment.

As long as PATH is configured, you can easily execute a program from
any location by calling EXEC with MD = 2, followed by MD = 0 or 1.

	MD = 3

Loads, but does not execute, the program specified by FIL.

P1 is the load address and P2 is the limit address.

The return value, if positive, will be the length of the program.
If negative, the return value is an error code.

The upper 8 bits of FIL should typically be set to 0, but they can
be used to modify the loading behavior if set to the following values:
 0 : Load according to the extension (.R, .Z, .X)
 1 : Load as an R-type file
 2 : Load as a  Z-type file
 3 : Load as an X-type file

	MD = 4

Used to execute a program loaded with MD = 1.
FIL contains the execution address.


$FF4C ; EXIT2(CODE) Ends the program with a given exit code

Example:
	MOVE.W	#CODE,-(SP)
	DC.W	_EXIT2

Returns: Nothing

Ends the program with the exit code specified by CODE.

Closes all open file handles, including those opened by child processes.


$FF4D ; WAIT() Obtains the process exit code

Example:
	DC.W	_WAIT

Returns:
	D0.L	Exit code

Returns the process exit code in D0.L

[My impression of this is that it is intended to be used immediately
after executing a sub-program via EXEC() or the like. So you'd put
the WAIT call afterwards to "wait" for it to finish, even though
it does no such thing.]


$FF4E ; FILES(FILEBUF,NAMEPTR,PTR) Search for files (first file only)

Example:
	MOVE.W	#ATR,-(SP)
	PEA	NAMEPTR
	PEA	FILBUF
	DC.W	_FILES
	LEA	10(SP),SP
	...
NAMEPTR:DC.B	'*.DOC',0

FILBUF:	DC.B	ATR
	DC.B	DRIVENO
	DC.W	DIRCLS
	DC.W	DIRFAT
	DC.W	DIRSEC
	DC.W	DIRPOS
	DC.B	FILENAME(8)
	DC.B	EXT(3)
	DC.B	ATR
	DC.W	TIME
	DC.W	DATE
	DC.L	FILELEN
	DC.B	PACKEDNAME(18,3),0
	* Total: 53 bytes

Returns:
	D0.L	Error code

Searches for a file (specified by NAMEPTR) which has the attributes
given by ATR, and writes its information to the FILEBUF buffer.

Wild cards are permitted for NAMEPTR.

The meaning of each ATR bit is as follows.
When 2 or more bits are set, upon searching either of those bits,
the operation ends (OR)

The individual bits of ATR are defined as follows:
 15 to 06 : Ignored
 05 : A - Archive
 04 : D - Directory name
 03 : V - Volume name
 02 : S - System file
 01 : H - Hidden file
 00 : R - Read-only file

If multiple attributes are specified, any of them will satisfy the
search criteria, if found. For example, if ATR is 6, this subroutine
will search for files that have the S bit and/or H bit set.

Note that you cannot restore the stack with a single ADDQ.L
after this call returns; it is recommended to use LEA instead.


$FF4F ; NFILES(FILBUF) Search for files (subsequent)

Example:
	PEA	FILBUF
	DC.W	_NFILES
	ADDQ.L	#4,SP
	...
FILBUF:	DC.B	ATR
	DC.B	DRIVENO
	DC.W	DIRCLS
	DC.W	DIRFAT
	DC.W	DIRSEC
	DC.W	DIRPOS
	DC.B	FILENAME(8)
	DC.B	EXT(3)
	DC.B	ATR
	DC.W	TIME
	DC.W	DATE
	DC.L	FILELEN
	DC.B	PACKEDNAME(18,3),0
	* Total: 53 bytes

Returns:
	D0.L	Error code

Uses the FILBUF requested by FILES ($FF4E) and searches
for the next file the meets the search criteria.


$FF50 ; SETPDB(PDBADR) Management process switch

Example:
	MOVE.L	PDBADR,-(SP)
	DC.W	_SETPDB
	ADDQ.L	#4,SP
	...
PDBADR:	DC.L	X	* Must contain the address received from GETPDB

Returns:
	D0.L	Previous PDBADR

Changes management to the process defined by PDBADR.

PDBADR is the start address of the program - $F0.
It must be obtained through GETPDB ($FF51).

Returns the previous PDBADR in D0.


$FF51 ; GETPDB() Obtain information about the current process

Example:
	DC.W	_GETPDB
	MOVE.L	D0,PDBADR
	...
PDBADR:	DC.L	X

Returns:
	D0.L	Current PDBADR

Obtains the PDBADR representing the current process in D0.

PDBADR is the start address of the program - $F0.


$FF52 ; SETENV(SETNAME,ENV,SETLINE) Sets an environment variable

Example:
	PEA	SETLINE
	CLR.L	-(SP)		* Current environment
	PEA	SETNAME
	DC.W	_SETENV
	LEA	12(SP),SP
	...
SETNAME:DC.B	'file',0
SETLINE:DC.B	'TEMP.TXT',0

Returns:
	D0.L	Error code if negative

Sets the environment variable SETNAME to a string contained in SETLINE.
ENV is a pointer to the environment, or 0 for the current environment.

If SETLINE is 0, the environment variable SETNAME is expunged.
Environment variables can contain up to 255 bytes.


$FF53 ; GETENV(GETNAME,ENV,GETBUF) Reads an environment variable

Example:
	PEA	GETBUF
	CLR.L	-(SP)
	PEA	GETNAME
	DC.W	_GETENV
	LEA	12(SP),SP
	...
GETNAME:DC.B	'file',0
GETBUF:	DS.B	256

Returns:
	D0.L	Error code if negative

Obtains the contents of the variable GETNAME from environment ENV,
and writes it to the buffer given by GETBUF. If ENV is 0, the current
environment will be used, as demonstrated in the example.

The buffer must comprise at least 256 bytes.

The following would be the result of the above example,
assuming that the SETENV example was executed prior.

GETBUF:	DC.B	'TEMP.TXT',0
	DS.B	247		* Unused remainder of the buffer


$FF54 ; VERIFYG() Checks the state of the verify flag

Example:
	DC.W	_VERIFYG

Returns:
	D0.L	State of the verify flag

Checks the state of the verify flag.

The return value is interpreted as follows:
 0 : No verification
 1 : Verification


$FF55 ; COMMON(MD,..) *Manipulates common areas

Example:
	MOVE.L	#LEN,-(SP)
	PEA	BUFFER
	MOVE.L	#POS,-(SP)
	PEA	NAME
	MOVE.W	#3,-(SP)	* MD = 3
	DC.W	_COMMON
	LEA	18(SP),SP
	...
NAME:	DC.B	'COMAREA',0
BUFFER:	DS.B	1024		* Size is arbitrary

Returns:
	<MD=0>	  D0.L	Size of common area in bytes
			Error code if negative
	<MD=1,2>  D0.L	Number of bytes actually read/written
			Error code if negative
	<MD=3..5> D0.L	Error code


This DOS call simplifies communication between processes.
The action taken varies depending on the value of MD:

	MD = 0	COMMON(MD,NAME)

Checks whether or not there is a common area denoted by NAME.

If such an area exists, the size in bytes is returned in D0.L,
else  a negative error code is returned.

	MD = 1	COMMON(MD,NAME,POS,BUFFER,LEN)

Reads LEN bytes at offset POS from common area NAME into BUFFER.

Returns either the number of bytes read or a negative error code.

	MD = 2	COMMON(MD,NAME,POS,BUFFER,LEN)

Writes LEN bytes from BUFFER at offset POS to common area NAME.

If the common area indicated by NAME does not exist,
a new one will be created prior to writing the data.

Specify a LEN of 0 to trim the common area.

Returns either the number of bytes written or a negative error code.

	MD = 3	COMMON(MD,NAME,POS,ID_PSP,LEN)

LEN bytes of common area NAME at POS are tagged by ID_PSP and locked.
Subsequent access to the region is prohibited by any entity aside from
the process specified by ID_PSP.

Returns an error code in D0.

	MD = 4	COMMON(MD,NAME,POS,ID_PSP,LEN)

LEN bytes of common area NAME at POS are unlocked and global access
to the region is restored. Returns an error code in D0.

	MD = 5	COMMON(MD,NAME)

Deletes the common area specified by NAME. Returns an error code in D0.


$FF56 ; RENAME(OLD,NEW) Renames/moves a file

Example:
	PEA	NEW
	PEA	OLD
	DC.W	_RENAME
	ADDQ.L	#8,SP
	...
NEW:	DC.B	'TEST.DOC',0
OLD:	DC.B	'TEST.BAK',0

Returns: D0.L Error Code

Takes the file named OLD and changes the name to NEW.

When the paths of OLD and NEW differ, the file is moved.

You cannot move files between different drives; however, as long as
the directory names are the same, the file can still be renamed,
but the move will not take place.


$FF57 ; FILEDATE(FILENO,DATETIME) Reads/sets a file's date and time

Example:
	MOVE.L	#DATETIME,-(SP)
	MOVE.W	#FILENO,-(SP)
	DC.W	_FILEDATE
	ADDQ.L	#6,SP

Returns:
	D0.L	The file's date and time, if the DATETIME argument is 0
		If the top word is $FFFF, it indicates an error.
		Other negative values are valid results, not errors.
		(This behavior is peculiar to this DOS call.)

Reads/sets the date and time of the file
associated with the file handle FILENO.

If DATETIME  = 0, the file date/time will be read.
If DATETIME <> 0, the file date/time will be set to DATETIME.

The bit format of DATETIME and the return value are as follows:
 31 to 25 : Year - 1980 (0 to 119)  [DOSCALL say 99, could be up to 127]
 24 to 21 : Month (1 to 12)
 20 to 16 : Day (1 to 31)
 15 to 11 : Hour (0 to 23)
 10 to  6 : Minute (0 to 59)
  5 to  0 : Second (0 to 29 double seconds)

The seconds are specified with a precision of two seconds.

If DATETIME=0, D0.L receives the date and time of the file.
If the highest 16 bits of the return value are $FFFF, an error occurred.
Be aware that every other negative number represents a valid date/time.


$FF58 ; MALLOC2(MD,LEN) *Allocates memory through the specified method

Example:
	MOVE.L	#LEN,-(SP)
	MOVE.W	#MD,-(SP)
	DC.W	_MALLOC2
	ADDQ.L	#6,SP

Returns:
	D0.L             Pointer to the allocated memory block
	D0.L = $81xxxxxx Insufficient RAM (x is the amount available)
	D0.L = $8200000? Memory allocation impossible (? indeterminate)

Allocates LEN bytes of memory and returns the pointer.
Only the lower 24 bits of LEN are valid.

MD specifies the mode to determine the method of memory allocation:
 MD = 0 Searches from the bottom up
 MD = 1 Takes the allocation from the smallest memory region possible
 MD = 2 Searches from the top down

If the allocation fails and the return value is of the form $81000000+,
the maximum number of bytes that could have been allocated is contained
in the lower 24 bits. If the return code is of the form $8200000?
(where ? represents an indeterminate value), no allocation is possible.


$FF5A ; MAKETMP(NAMEPTR,ATR) *Creates a temporary file

Example:
	MOVE.W	#ATR,-(SP)
	PEA	NAMEPTR
	DC.W	_MAKETMP
	ADDQ.L	#6,SP
	...
NAMEPTR:DC.B	'A:\SAMPLE\TMP???.TXT'

Returns:
	D0.L	File handle of the created file or negative on error

Creates a temporary file in the path specified by NAMEPTR.

The following is an example of a proper file name:

 A:\SAMPLE\FILE????.TXT

The part of the file name indicated by "????" is replaced with a unique
number from "0000" to "9999". If the file name contains a number instead
of question marks, then the algorithm searches for a unique file name
starting with that number.

Please keep in mind that the path string pointed to by NAMEPTR will be
rewritten by this call.

ATR specifies the file attributes of the temporary file to be created.
(See the CHMOD documentation for further information.)

If the temporary file is created successfully, its file handle
is returned in D0.L. If an error occurs, a negative value will
be returned instead.


$FF5B ; NEWFILE(NAMEPTR,ATR) *Creates a file

Example:
	MOVE.W	#ATR,-(SP)
	PEA	NAMEPTR
	DC.W	_NEWFILE
	ADDQ.L	#6,SP
	...
NAMEPTR:DC.B	'A:\DOC\TEST.DOC',0

Returns:
	D0.L	File handle of the created file or a negative error code
	D0.L = -80 : The specified file already exists

Creates a new file. If the file with the file name specified by NAMEPTR
already exists, an error code is returned.

ATR specifies the file attributes of the file to be created.
(See the CHMOD documentation for further information.)

If the file is created successfully, its file handle is returned in D0.
If an error occurs, a negative value will be returned instead.

The difference between NEWFILE and CREATE ($FF3C) is that CREATE will
overwrite a preexisting file whereas NEWFILE will halt the operation
and return an error code.


$FF5C ; LOCK(MD,FILENO,OFFSET,LEN) *File locking

Example:
	MOVE.L	#LEN,-(SP)
	MOVE.L	#OFFSET,-(SP)
	MOVE.W	#FILENO,-(SP)
	MOVE.W	#MD,-(SP)
	DC.W	_LOCK
	LEA 12(SP),SP

Returns:
	D0.L	Error code

Locks or unlocks access to the specified file.

A file lock grants exclusive control to the access of a file
such that file operations by other processes are forbidden.

MD = 0	Locks the specified region of the file
MD = 1	Unlocks the region

The region in question encompasses LEN bytes starting at OFFSET.


$FF5F ; ASSIGN(MD,...) *Manipulates virtual drives/directories

Example:
	PEA	BUFF2
	PEA	BUFF1
	MOVE.W	#MD,-(SP)
	DC.W	_ASSIGN
	LEA	10(SP),SP
	...
BUFF1:	DC.B	'A:\LIB',0
BUFF2:	DS.B	256

Returns:
	<MD=0>
	D0.L	Assignment mode or error code if negative
	 = $40	There is no assignment
	 = $50	Assignment of the virtual drive
	 = $80	Assignment of the virtual directory

	<MD=1,4>
	D0.L	If negative, indicates that an error occurred

Obtains/changes/cancels the assignment list
of the specified virtual drive/directory.

The operation varies depending on the value of MD:

	MD = 0	ASSIGN(0,BUFF1,BUFF2) Obtains the assignment list

BUFF1 specifies the name of the drive.
BUFF2 points to a storage area to receive the name of the directory.

On success, the return value will be one of the assignment modes (MODE)
shown below. A negative number is an error code.

 MODE = $40 : There is no assignment

BUFF2 is set to the current directory of the drive specified by BUFF1.

 MODE = $50 : The assignment is for a virtual drive

When accessing BUFF1, the directory actually accessed will be BUFF2.

 MODE = $60 : The assignment is for a virtual directory

Sets BUFF2 to the directory that must be accessed when attempting
to virtually access BUFF1.

	MD = 1	ASSIGN(1,BUFF1,BUFF2,MODE) Creates the assignment list

BUFF1 specifies the name of the drive.
BUFF2 specifies the name of the directory which is being assigned.
MODE specifies the assignment mode as shown below:

 MODE = $50 : The assignment is for a virtual drive

Access to the drive given by BUFF1 will redirect to directory BUFF2.

 MODE = $60 : The assignment is for a virtual directory

Access to the directory given by BUFF1 will redirect to directory BUFF2.

An error condition is indicated by a negative number.

	MD = 4	ASSIGN(4,BUFF1) Cancels the assignment list

BUFF1 specifies the name of the virtual drive/directory.

An error condition is indicated by a negative number.


$FF7D ; S_MALLOC(MD,LEN) *Allocates memory under main memory management

Example:
	MOVE.L	#LEN,-(SP)
	MOVE.W	#MD,-(SP)
	DC.W	_S_MALLOC
	ADDQ.L	#6,SP

Returns:
	D0.L             Pointer to the allocated memory block
	D0.L = $81xxxxxx Insufficient RAM (x is the amount available)
	D0.L = $8200000? Memory allocation impossible (? indeterminate)


Allocates a memory block of LEN bytes under main memory management.
Only the lower 24 bits of LEN are valid.

MD specifies the mode to determine the method of memory allocation:
 MD = 0 Searches from the bottom up
 MD = 1 Takes the allocation from the smallest memory region possible
 MD = 2 Searches from the top down

Returns the pointer of the secured memory block in D0. The memory
management pointer will be at -$10 relative to the returned value.

If the allocation fails and the return value is of the form $81000000+,
the maximum number of bytes that could have been allocated is contained
in the lower 24 bits. If the return code is of the form $8200000?
(where ? represents an indeterminate value), no allocation is possible.

You should not use S_MALLOC in normal application programs.
Programs using S_MALLOC must be booted by the OS and can't be terminated
(i.e. resident processes which never call EXIT or EXIT2).


$FF7E ; S_MFREE(MEMPTR) *Deallocates memory under main memory management

Example:
	PEA	MEMPTR
	DC.W	_S_MFREE
	ADDQ.L	#4,SP

Returns:
	D0.L	Error code

Deallocates a memory block under main memory management.

MEMPTR must be a pointer returned by MALLOC ($FF48) or S_MALLOC ($FF7F)
(the pointer to the allocated memory block).

If MEMPTR is the sub memory management pointer specified by S_PROCESS
($FF7F) and if the corresponding thread ID is the current ID, it will
delete the process with KILL_PR ($FFF9).

In such cases, processes (thread IDs) which terminate and stays resident
under sub memory management will enter main memory management.

Do not call S_MFREE when there is an active program in the memory block
specified by MEMPTR.

When MEMPTR = 0, all allocated memory will be freed including child
processes and memory allocated by them.


$FF7F ; S_PROCESS(ID,START,...) *Sets sub memory management

Example:
	MOVE.L	#I_LEN,-(SP)
	MOVE.L	#LENGTH,-(SP)
	PEA	START
	MOVE.W	#ID,-(SP)
	DC.W	_S_PROCESS
	LEA	14(SP),SP

Returns:
	D0.L		Pointer to first memory block (of size I_LEN)
	 = $FFFF00??	ID error (?? is the highest valid value for ID)
	 = -14		Indicates that LENGTH is less than I_LEN+16

Sets the sub memory management to the specified header address (START)
and amount of bytes (LENGTH).

From this point forward, memory allocation requests from the thread
(process) of the specified ID will be limited to this memory area.

When establishing the new sub memory management, only 1 block will be
allocated for sure, of size I_LEN.

The first 16 bytes of START will be consumed by the memory management
pointers.

Since an ID of 0 represents the main thread, it cannot be used.


$FFF3 ; DISKRED(ADR,DRIVE,SECT,SECTLEN) Reads from block device directly

Example:
	MOVE.W	#SECTLEN,-(SP)
	MOVE.W	#SECT,-(SP)
	MOVE.W	#DRIVE,-(SP)
	MOVE.L	#ADR,-(SP)
	DC.W	_DISKRED
	LEA	10(SP),SP

Returns: Nothing

Reads SECTLEN sectors directly from the block device specified by DRIVE,
starting with sector number SECT. The data will be written to the buffer
pointed to by ADR.

Because the reading is carried out in sector units, the buffer pointed
to by ADR should be a multiple of 1024 bytes in length.

SECTLEN = 1 to ? (differs depending on the media)
SECT    = 0 to ? (differs depending on the media)

DRIVE is specified as follows:
 DRIVE = 0 : Current drive
 DRIVE = 1 : A drive
 DRIVE = 2 : B drive
 DRIVE = 3 : C drive


$FFF4 ; DISKWRT(ADR,DRIVE,SECT,SECTLEN) Writes to block device directly

Example:
	MOVE.W	#SECTLEN,-(SP)
	MOVE.W	#SECT,-(SP)
	MOVE.W	#DRIVE,-(SP)
	MOVE.L	#ADR,-(SP)
	DC.W	_DISKWRT
	LEA	10(SP),SP

Returns: Nothing

Writes SECTLEN sectors directly to the block device specified by DRIVE,
starting at sector number SECT. The data will be taken from the buffer
pointed to by ADR.

Because the writing is carried out in sector units, the buffer pointed
to by ADR should be a multiple of 1024 bytes in length.

SECTLEN = 1 to ? (differs depending on the media)
SECT    = 0 to ? (differs depending on the media)

DRIVE is specified as follows:
 DRIVE = 0 : Current drive
 DRIVE = 1 : A drive
 DRIVE = 2 : B drive
 DRIVE = 3 : C drive


$FFF5 ; INDOSFLG() *Returns a pointer to the OS internal work space

Example:
	DC.W	_INDOSFLG

Returns:
	D0.L	Pointer to INDOS_FLG

Returns a pointer to the OS internal work space.

Please keep in mind that because the above is a supervisory area,
it cannot be accessed in user mode.

The return value will point to INDOS_FLG.

INDOS_FLG is a flag which indicates whether or not the current DOS call
is being executed. Because this is a work area critical to the OS,
it must never be modified directly.

The contents of INDOS_FLG are as follows:

indosf:		ds.w	* OS execution level
doscmd:		ds.b	* OS execution function number
fat_flg:	ds.b	* FAT search mode (0=standard, else from start)
retry_count:	ds.w	* I/O retry count (normally 3 times)
retry_time:	ds.w	* I/O retry wait time; normally 100 (1 second)
verifyf:	ds.w	* Verify mode (0=off, 1=on)
breakf:		ds.b	* Break mode (0=off, 1=on)
ctrlpf:		ds.b	* CTRL-P mode (0=off, 1=on)
		ds.b	* Used by the system
wkcurdrv:	ds.b	* Current drive (0:A, etc.)


$FFF6 ; SUPER_JSR(JMPADR) *Call programs in the supervisor area

Example:
	PEA	JMPADR
	DC.W	_SUPER_JSR
	ADDQ.L	#4,SP

Returns:
	D0-D7/A0-A6	(Dependent on the called program)

Used to execute a JSR (Jump to SubRoutine) into programs contained
within the supervisor area. JMPADR specifies the entry address.

The values contained in registers D0-D7/A0-A6 prior to this call are
passed to the invoked subroutine. When control returns to the caller,
the above registers will be in the same state as the called subroutine
left them. SP, however, will be in its pre-call state.

The stack cannot be used to pass arguments, since it is indeterminate
how SSP/USP will appear to the called program.

This DOS call will not handle exceptions resulting from the JSR.

You cannot change the entry of this DOS call with INTVCS ($FF25).


$FFF7 ; BUS_ERR(S_ADR,D_ADR,MD) *Checks if address can be read/written

Example:
	MOVE.W	#MD,-(SP)
	PEA	D_ADR
	PEA	S_ADR
	DC.W	_BUS_ERR
	LEA	10(SP),SP

Returns:
	D0.L =  0	Addresses can be safely read/written
	D0.L =  1	Bus error will occur when writing to D_ADR
	D0.L =  2	Bus error will occur when reading from S_ADR
	D0.L = -1	Error (bad arguments)

Attempts to read and write the addresses specified by S_ADR and D_ADR
respectively, in order to check for bus errors.

Before accessing a supervisor area, or an area where nothing has been
mapped, or an area where a bus error could arise, you can use this DOS
call to check beforehand whether reading and writing are possible.

The correct mode is selected as follows:
 MD = 1 Read and write at the byte level
 MD = 2 Read and write at the word level
 MD = 3 Read and write at the longword level

D0.L will receive a value indicating how the bus error, if any, arose,
or -1 if an error occurred. The latter can happen if the value of MD
is invalid, or if S_ADR and D_ADR are odd and word or longword access
is requested.

This call entry cannot be changed with INTVCS ($FF25).


$FFF8 ; OPEN_PR(NAME,COUNT,..) *Registers a background task

Example:
	MOVE.L	#SLEEP_TIME,-(SP)
	PEA	BUFF
	PEA	INIT_PC
	MOVE.W	#INIT_SR,-(SP)
	PEA	INIT_SSP
	PEA	INIT_USP
	MOVE.W	#COUNT,-(SP)
	PEA	NAME
	DC.W	_OPEN_PR
	LEA	28(SP),SP
	...
BUFF:	DC.L	LENGTH		* Amount of data in the buffer
	DC.L	DATABUF_ADR	* Pointer to the data buffer
	DC.W	COMMAND		* Command number
	DC.W	ID		* ID of other party (-1 allows commun.)

Returns:
	D0.L		Thread ID of the registered task
	D0.L <   0	Error code
	D0.L = -27	A task with the same name already exists
	D0.L = -29	Additional tasks cannot be registered

Registers a background task. The registered thread goes into sleep mode.

NAME represents a pointer to a string of fewer than 15 characters which
defines the name of the thread. An error occurs if it has the same name
as a thread which is currently running.

COUNT defines the number of timer interrupts that must occur before
a task switch takes place. The value can range from 2 to 255. Values
of 0 or 1 will be treated as 2.

INIT_USP, INIT_SSP, and INIT_PC are the initial values of their
respective registers when executing the registered task. Six kilobytes
are necessary for the system stack. INIT_SR can be $0000 or $2000 to
select user mode or supervisor mode. All other registers default to 0.

BUFF points to a buffer used for inter-task communication.

SLEEP_TIME specifies the wait time in milliseconds. Pass 0 for this
argument and the task will sleep forever.

Threads registered as background tasks by OPEN_PR terminate and stay
resident with KEEPPR ($FF31). Use KILL_PR ($FFF9) to remove a thread
from memory.

The registered background task thread ID is returned. A negative number
indicates an error code.


$FFF9 ; KILL_PR() *Deletes the current process

Example:
	DC.W	_KILL_PR

Returns:
	D0.L	Error code

Deletes the current process.

For processes which terminate and stay resident, this call deletes
all threads with the same process ID and frees the allocated memory.
Furthermore, all open files will be closed. You will need to restore
modified vectors to their original values yourself.

When ending a process (with EXIT, EXIT2, etc.) after having started
registered threads, you must first delete (with KILL_PR) the threads
opened by said process.

The aforementioned behavior is not guaranteed when executing KILL_PR
on the process of the main thread.

To delete foreign processes, send a KILL command using SEND_PR ($FFF0).


$FFFA ; GET_PR(ID,BUFF) *Obtains thread maintenance information

Example:
	PEA	BUFF
	MOVE.W	#ID,-(SP)
	DC.W	_GET_PR
	ADDQ.L	#6,SP
	...
BUFF:	DS.B	116

Returns:
	D0.L	Thread ID or an error code if negative

Copies maintenance information of the thread indicated by ID to BUFF.

If you specify -1 for ID and write the thread's name to BUFF+96,
the corresponding thread ID will be returned and its management
information will be copied to BUFF. Specify -2 for the current thread.

The format of the management information is as follows:

	DC.L	NEXT_PTR	* Management info of the next thread
	DC.B	WAIT_FLG	* Normal=$00, wait=$FF
	DC.B	COUNT		* Subtracted at every interrupt
	DC.B	MAX_CNT		* COUNT initial value
	DC.B	DOSCMD		* DOS call number
	DC.L	PSP_ID		* Process ID
	DC.L	USP
	DC.L	D0,D1,D2,D3,D4,D5,D6,D7
	DC.L	A0,A1,A2,A3,A4,A5,A6
	DC.W	SR
	DC.L	PC
	DC.L	SSP
	DC.W	INDOSF		* System reserved
	DC.L	INDOSP		* System reserved
	DC.L	BUFF		* Inter-task communication buffer
	DS.B	16		* Name of the thread
	DC.L	WAIT_TIME	* Remaining wait time (milliseconds)

The return value is the thread ID if positive, else an error code.


$FFFB ; SUSPEND_PR(ID) *Force the specified thread into sleep mode

Example:
	MOVE.W	#ID,-(SP)
	DC.W	_SUSPEND_PR
	ADDQ.L	#2,SP

Returns:
	D0.L =  0		Successful completion
	D0.L <  0		Error code
	D0.L = -1		Error with the thread itself
	D0.L = $FFFF00??	Bad ID (?? is the highest valid ID)

Suspends the thread corresponding to the specified ID.

Threads which have been suspended will sleep until they are woken up
by SEND_PR ($FFFD).

A return value of 0 indicates that the call completed successfully.
A negative number is an error code.
If the ID is invalid, $FFFF00?? will be returned, with the lowest
8 bits representing the highest valid thread ID. If there is an
error with the thread itself, -1 will be returned.


$FFFC ; SLEEP_PR(TIME) *Enters sleep mode

Example:
	MOVE.L	#TIME,-(SP)
	DC.W	_SLEEP_PR
	ADDQ.L	#4,SP

Returns:
	D0.L		Indicates the state of the thread
	D0.L = -1	The wait time has expired; woken by self
	D0.L = -2	The wait time has expired; woken by SEND_PR
	D0.L = (else)	Wait time remaining (woken by SEND_PR)

Enters sleep mode.

TIME specifies the wait time, or 0 to sleep forever.

Sleeping threads can be woken up prematurely by SEND_PR ($FFFD).
If the SEND_PR ($FFFD) command is $FFFB, the inter-task communication
buffer will not be disturbed. When using other commands, the buffer
will be set as follows:

BUFF:	DC.L	LENGTH		* Number of bytes written to the buffer
	DC.L	DATABUF_ADR	* Pointer to the data buffer
	DC.W	COMMAND 	* Command number
	DC.W	ID		* ID of the thread which was woken up

Before reentering sleep mode, you must initialize the data buffer
pointer and length, and set the ID to -1, after processing the contents
of the data buffer. This permits communication from other threads.

Even when not in sleep mode, there are instances where data can be
received from SEND_PR ($FFF0). In this case, the thread will be awoken
immediately after entering sleep mode, and the full wait time argument
value will be returned.

The return value (D0.L) is interpreted as follows:

 D0.L = -1
Indicates that the wait time has expired and that the thread woke up
by itself (i.e. no SEND_PR message received.) The contents of the
inter-task communication buffer remain undisturbed in this case.

 D0.L = -2
The wait time has expired, but the thread was woken by SEND_PR ($FFFD)
after having been stopped by SUSPEND_PR ($FFFB). The inter-task
communication buffer will be filled in according to SEND_PR ($FFFD).

 D0.L = (any other value)
The wait time has not yet expired; the thread was woken up by SEND_PR.
In this case, the return value represents the remaining wait time in
milliseconds. The contents of the buffer are set according to SEND_PR.


$FFFD ; SEND_PR(MY_ID,YOUR_ID,..) *Sends commands or data to a thread

Example:
	MOVE.L	#U_LEN,-(SP)
	PEA	U_BUFF
	MOVE.W	#CMDNO,-(SP)
	MOVE.W	#YOUR_ID,-(SP)
	MOVE.W	#MY_ID,-(SP)
	DC.W	_SEND_PR
	LEA	14(SP),SP

Returns:
	D0.L =   0	 Successful completion
	D0.L <   0	 Error code
	D0.L = -28	 Writing error
	D0.L = $FFFF00?? Bad ID (?? is the higest valid ID)
	D0.L = $800????? Bad U_LEN (????? is the greatest valid value)

Sends commands and data to a thread, waking it from sleep mode.

MY_ID is the ID of the calling thread while YOUR_ID is the ID of the
thread to communicate with.

CMDNO (command number) is a word value that informs the recipient which
type of message is being sent. Any command value beyond those defined
by the system must be coordinated by the threads.

System commands are of the form $FF?? and are defined as follows:

	$FFF9 : Request to delete the thread

	$FFFB : Only used to wake up a thread from forced sleep state
With this command, the inter-task communication buffer remains the same.

	$FFFC : Request to sleep
When this command is sent, upon waking the thread should immediately
change YOUR_ID to -1 and go back to sleep. Normally used for monitoring
the communication buffer without sleeping.

	$FFFF : Command used to check if processing has ended
If -28 is returned, it indicates that it is still processing.

The inter-task communication buffer is used to transfer commands/data.
The structure of the communication buffer is as follows:

BUFF:	DC.L	LENGTH		* Number of bytes written to the buffer
	DC.L	DATABUF_ADR	* Pointer to the data buffer
	DC.W	COMMAND 	* Command number
	DC.W	ID		* ID of the thread which was woken up

If the ID field of the communication buffer of the thread represented
by YOUR_ID has been set to -1, then, since the buffer is writable,
MY_ID and CMDNO should respectively be set to YOUR_ID and COMMAND
(both from the communication buffer), and only U_LEN to the data from
U_BUFF, and write to the data buffer given by DATABUF_ADR.

U_LEN should be set to the LENGTH of the communication buffer.

This command wakes up the target thread, if it is asleep.


The $FFFB command is treated specially by only waking up the specified
thread, and the other buffers will not be modified, even if YOUR_ID of
the communication buffer is not -1.

When U_LEN of the argument is greater than the LENGTH of the inter-task
communication buffer, an error occurs. It is also an error if writing
is prohibited.

On successful completion, 0 is returned.

In the event of a write error, -28 is returned.

If error code $FFFF00?? is returned, it means that the specified ID
is invalid and ?? will be the highest valid ID value.

If error code $800????? is returned, it means that the specified U_LEN
is invalid and ????? represents the highest possible value of U_LEN.


$FFFE ; TIME_PR() *Returns the counter value of the current timer

Example:
	DC.W	_TIME_PR

Returns:
	D0.L	Current timer count

Returns the current timer counter value (in milliseconds) in D0.

When several background threads are active in parallel, in order to
measure a block of time regardless of which thread is active,
it is necessary to have a counter which evens everything out.

Since the counter wraps around to zero if its magnitude exceeds 32 bits,
it is possible to calculate the elapsed time simply by subtracting the
counter value of the timer from the previous time.


$FFFF ; CHANGE_PR() *Yields to other background tasks

Example:
	DC.W	_CHANGE_PR

Returns:
	Nothing

Causes the current background task to yield the remainder of its
processing quantum and switches to the next task.


------------------------------------------------------------------------


Values known as "file handles" are used to access files in Human68k.
The value of a file handle is treated as a 16-bit quantity stored in
a single word variable, which is similar to the BASIC file numbering
scheme (see the fopen function).

When a file is successfully created/opened with DOS calls $FF3C/$FF3D,
a file handle is associated with that file. Thereafter, the open file
is accessed exclusively through that file handle.

In Human68k, consoles, printers, and other devices are considered files,
even when opened with reserved file names. Therefore they receive the
same kind of file handle as standard files do when opened.

Because the five file handles listed below are kept open by default
(reserved by the system), there is no need to open them explicitly.
Refer to the "Human68k User's Manual", which is included with your
machine, to find out more about standard input/output, redirection, etc.

Handle	Name and Standard Device Name
 0	Standard Input  (normally CON, redirect possible)
 1	Standard Output (normally CON, redirect possible)
 2	Standard Error Output (normally CON)
 3	Standard Auxiliary Output (AUX)
 4	Standard Printer Output (PRN)

When creating/opening normal files under Human68k, the lowest remaining
unused (or previously freed) file handle is allocated to the file.
File handle values range from 0 to the number defined by the FILES=
variable in CONFIG.SYS (up to 93), but since five of these handles are
reserved for standard devices, the actual number of file handles which
are available for user programs is five less than the FILES variable.

When an error arises during the execution of a DOS call, the high-order
bit of the return code is set to 1 (creating a negative value).
The remaining bits define the error code, as shown in the table below.

Value	Meaning
 -1	Invalid function code executed
 -2	Could not find the specified file name
 -3	Could not find the specified directory
 -4	Too many open files
 -5	Cannot access the directory / volume label
 -6	The specified handle is not open
 -7	The memory management area has become corrupted
 -8	Insufficient memory for execution
 -9	Invalid memory pointer
-10	Illegal environment specified
-11	Abnormal executable file format
-12	Abnormal access mode when opening
-13	Erroneous file name
-14	Invalid call parameter
-15	Erroneous drive designation
-16	Cannot delete the current directory
-17	The device is incapable of IOCTRL
-18	Could not find any more files
-19	This file is not writable
-20	This directory has already been registered
-21	Cannot delete because a file is present
-22	Cannot rename because a file with the same name already exists
-23	Cannot create a file because the disk is full
-24	Cannot create a file because the directory is full
-25	Unable to seek to the specified position
-26	Supervisor mode specified while already in supervisor mode
-27	Thread name already exists
-28	Writing to the process communication buffer currently prohibited
-29	Cannot start any more background processes
-32	Insufficient lock area
-33	Access denied due to lock
-34	The handler for the specified drive is open
-80	File exists

When a user program is launched by the system, all the parameters
required for execution are placed in the processor's register set
before control is handed over to the user program. Therefore, generally
speaking, it is unnecessary to directly reference the contents of
memory management pointers, environment structures, process management
pointers, and the like, which are explained hereafter.

@Registers

 A0 = Address of the program's memory management pointer
 A1 = Address of the end of the program (DATA and BSS included) + 1
 A2 = Address of the command line passed to the program
 A3 = Address of the environment
 A4 = Address of the program execution header
 SR = Mode (user mode)
 USP = Same as parent's stack pointer
 SSP = System stack

The values of the remaining registers are indeterminate.

@Memory

Initially, the maximum amount memory available is already allocated.
Therefore you will not be able to use MALLOC without first freeing
memory by calling SETBLOCK.

The end address of the memory given to this process is at 8(A0)
(i.e. contained within the memory management pointer).

If you are not going to execute child processes, then the contents
of registers A0 and A1 can be discarded.

@Command Line

Only the command line arguments (located after the name of the command)
are made available to the program when it is executed. They are stored
in the area pointed to by the A2 register.

The system processes "<", ">", and "|" for the purpose of redirection
and output piping, so they will not be included. Other characters such
as spaces, tabs, etc. remain as they are.

@Structure of the Command Line

The length of the string (in bytes) is indicated by the first byte.
A null character (0) is appended to the end of the command line.

Example:
	DC.B	7
	DC.B	'-W TEST',0

@Environment

The environment is pointed to by the A3 register initially. It is the
same as the parent environment, so whenever it is modified by SETENV,
the parent environment will also be changed.

To execute a child process under a different environment, the program
must allocate and prepare a new environment.

Programs that require nothing more than GETENV/SETENV can safely discard
the initial contents of the A3 register.

@Structure of the Environment

The size of the environment workspace is stored in the first four bytes.
It includes all the memory available, including the header and space for
new strings.

Each environment variable is terminated by a null character (0).
A second null byte will appear at the end of the last string.

Example:
	DC.L	??		* Length of the environment workspace
	DC.B	'path=A:\',0	* First string, terminated by 0
	DC.B	...		* (Additional null-terminated strings)
	DC.B	0		* End of all character strings
	DS.B	??		* Undefined (storage for more strings)


Memory Management Pointers

A single process is composed of numerous memory blocks (environment,
data area, the program itself, etc.). When the X68000 is active,
many processes are running, and many memory blocks are operational.
Memory management pointers exist to manage the memory resources of the
system in order to avoid memory interference between processes.

Processes are able to request memory from the system using MALLOC,
which allocates new memory blocks, or change the size of existing
memory blocks with the SETBLOCK function call.

Memory management pointers are automatically created by the system in
the header of each memory block. These pointers form a list structure
that comprises all the memory managed by the operating system.

Processes generally should only access properly allocated memory blocks.
User programs therefore do not need to be aware of the memory management
pointers, so long as they do not access any other memory.

The process management pointers are defined by the four long words
shown below. FSTMEM ($10A1A) within the OS area is the start.
Memory used to store management pointers must be aligned on a 16-byte
boundary, i.e. an address of which the 4 lowest bits are 0 ($XXXXX0).

$0	Previous memory management pointer
$4	Memory management pointer of the process that did the allocation
$8	Address of the end of this memory block + 1
$A	Next memory management pointer (or 0 if this is the end)


BPB Table

When drivers are initialized in a block device, data called the BPB
(BIOS Parameter Block) informs the system about the characteristics
of the disk that the driver is going to use.

From this data, the system internally creates a management table called
a DPB (Driver Parameter Block) and uses it to manage the drivers.

Since a BPB is needed on a per-unit basis, it sets up the address of
each BPB and prepares a BPB table which is used to communicate these
addresses to the system.

 Format of BPB (12 bytes)

$00  1W  Number of bytes per sector
$02  1B  Number of sectors per cluster
$03  1B  Number of FATs
$04  1W  Number of sectors in the reserved area
$06  1W  Number of entries in the root directory
$08  1W  Number of sectors in total
$0A  1B  Media byte
$0B  1B  Number of sectors used per FAT

 Format of DPB

$00  1B  Device number (0=A: 1=B: etc.)
$01  1B  Driver internal unit number
$02  1W  Number of bytes per sector
$04  1B  Number of sectors per cluster - 1
$05  1B  Sector number of header cluster
$06  1W  Sector number of first FAT
$08  1B  Number of FAT areas
$09  1B  Number of sectors used per FAT
$0A  1W  Number of entries in the root directory
$0C  1W  Head sector number of the data area
$0E  1W  Total clusters + 1
$10  1W  Head sector number of the root directory
$12  1L  Pointer to device driver
$16  1B  Media byte
$17  1B  Flag used by DPB (no access if -1)
$18  1L  Pointer to the next DPB
$1C  1W  Cluster number of the current directory
$1E 64B  Current directory's character buffer


Process Management Pointers

When a program is loaded into memory through an EXEC function call,
located right before the program area is a memory management pointers
(16 bytes) and the process management work area (240 bytes). The values
stored in these work areas represent the current state of the system
or the conditions given at the beginning of the process. They are also
returned to the parent process when the process ends.

** Memory Management Pointers (16 bytes) ** (Register A0)

$000 1L The previous memory management pointer
$004 1L Memory management pointer of the process secured by this memory
$008 1L Address of this memory block end +1
$00C 1L Next memory management pointer (ends if 0)

** Process Management Pointers (240 bytes) **

$010 1L Environment address given by process (stored in register A3)
$014 1L Return address when process ends
$018 1L Return address when process is stopped by a CTRL-C break
$01C 1L Return address when process is aborted due to an error
$020 1L Address of the command line passed to the process (register A2)
$024 3L Field of bits corresponding to 96 file handles. 1 = file in use.
$030 1L BSS address of this process
$034 1L Heap address (same as BSS) (register A1 = end of heap + 1)
$038 1L Default stack address of this process
$03C 1L USP register value of parent process
$040 1L SSP register value of parent process
$044 1W SR  register value of parent process
$046 1W SR  register value during abort (halt)
$048 1L SSP register value during abort (halt)
$04C 1L TRAP10 (POWER OFF or RESET processing routines)
$050 1L TRAP11 (HDOFF processing and other routines with the BREAK key)
$054 1L TRAP12 (HCOPY processing and other routines with the COPY key)
$058 1L TRAP13 (Setting of break flag with the CTRL-C key)
$05C 1L TRAP14 (Error display and abort/retry/ignore menu)
$060 1L Process flag (0 is for parent, -1 if started by OS)
$064 7L Unused ($64 ~ $7F)
$080 'A:'
$082 '\BIN\',0
$0C4 'COMMAND.X',0
$0DC Unused ($0DC~$0FF)
$100 Start of program

Authors:
 Takafumi Ichikawa (original)
 Toshio Ishizaka (version 2 supplement)

(EOF)